﻿//--------------------------------------------------------------------------
// 
//  Copyright (c) Chili Software.  All rights reserved. 
// 
//  File: IObjectNotification.cs
//
//  Description: Implemented to get notification on persistent activities.
// 
//--------------------------------------------------------------------------

using System;

namespace Chili.Opf3
{
	/// <summary>
	/// This interface is implemented by classes that need information on each change of
	/// their state.
	/// </summary>
	/// <remarks>
	/// Classes that need information about any change on their state have to implement
	/// this interface to get notified if their state changes. If the framework encounters a
	/// class implementing the interface the appropriate method is called while the state
	/// changes.
	/// </remarks>
	/// <example>
	///     The following example shows how to implement the interface in your own persistent
	///     classes.
	///     <code lang="CS">
	/// [Persistent("USER")]
	/// public class User : IObjectNotification
	/// {
	///     void IObjectNotifcation.OnBeforePopulated(ObjectNotificationEventArgs e)
	///     {
	///         // The method is called before the object is populated.
	///         // Any kind of checks could be done here, for example creating
	///         // a backup of the existing object.
	///     }
	///  
	///     // ... Other methods of the interface.
	///  
	///     // ... Other properties and code.
	/// }
	///     </code>
	/// </example>
	public interface IObjectNotification
	{
		/// <summary>
		/// Invoked by the framework before the persistent object is populated.
		/// </summary>
		/// <param name="e">
		/// Contains information about the state of the persistent object and the
		/// <see cref="Opf3.ObjectContext">ObjectContext</see> of the current operation.
		/// </param>
		void OnBeforePopulated(ObjectNotificationEventArgs e);

		/// <summary>
		/// Invoked by the framework after the object is populated.
		/// </summary>
		/// <param name="e">
		/// Contains information about the state of the persistent object and the
		/// <see cref="Opf3.ObjectContext">ObjectContext</see> of the current operation.
		/// </param>
		void OnAfterPopulated(ObjectNotificationEventArgs e);

		/// <summary>
		/// Invoked by the framework before the object is inserted.
		/// </summary>
		/// <param name="e">
		/// Contains information about the state of the persistent object and the
		/// <see cref="Opf3.ObjectContext">ObjectContext</see> of the current operation.
		/// </param>
		void OnBeforeInsert(ObjectNotificationEventArgs e);

		/// <summary>
		/// Invoked by the framework after the object is inserted.
		/// </summary>
		/// <param name="e">
		/// Contains information about the state of the persistent object and the
		/// <see cref="Opf3.ObjectContext">ObjectContext</see> of the current operation.
		/// </param>
		void OnAfterInsert(ObjectNotificationEventArgs e);

		/// <summary>
		/// Invoked by the framework before the object is updated.
		/// </summary>
		/// <param name="e">
		/// Contains information about the state of the persistent object and the
		/// <see cref="Opf3.ObjectContext">ObjectContext</see> of the current operation.
		/// </param>
		void OnBeforeUpdate(ObjectNotificationEventArgs e);

		/// <summary>
		/// Invoked by the framework after the object is updated.
		/// </summary>
		/// <param name="e">
		/// Contains information about the state of the persistent object and the
		/// <see cref="Opf3.ObjectContext">ObjectContext</see> of the current operation.
		/// </param>
		void OnAfterUpdate(ObjectNotificationEventArgs e);

		/// <summary>
		/// Invoked by the framework before the object is deleted.
		/// </summary>
		/// <param name="e">
		/// Contain information about the state of the persistent object and the
		/// <see cref="Opf3.ObjectContext">ObjectContext</see> of the current operation.
		/// </param>
		void OnBeforeDelete(ObjectNotificationEventArgs e);

		/// <summary>
		/// Invoked by the framework after the object is deleted.
		/// </summary>
		/// <param name="e">
		/// Contains information about the state of the persistent object and the
		/// <see cref="Opf3.ObjectContext">ObjectContext</see> of the current operation.
		/// </param>
		void OnAfterDelete(ObjectNotificationEventArgs e);

		/// <summary>
		/// Invoked by the framework after the object has been marked deleted.
		/// </summary>
		/// <param name="e">
		/// Contains information about the state of the persistent object and the
		/// <see cref="Opf3.ObjectContext">ObjectContext</see> of the current operation.
		/// </param>
		void OnBeforeMarkDeleted(ObjectNotificationEventArgs e);

		/// <summary>
		/// Invoked by the framework after the object has been marked deleted.
		/// </summary>
		/// <param name="e">
		/// Contains information about the state of the persistent object and the
		/// <see cref="Opf3.ObjectContext">ObjectContext</see> of the current operation.
		/// </param>
		void OnAfterMarkDeleted(ObjectNotificationEventArgs e);
	}
}
